~ chicken-core (master) /manual/Module (chicken base)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken base)56Core procedures and macros, acting as basic extensions to the R7RS7standard and other essential features.89This module is used by default, unless a program is compiled with10the {{-explicit-use}} option.1112=== Numeric predicates1314These allow you to make a more precise differentiation between number15types and their properties, not provided by R7RS.1617==== fixnum?1819<procedure>(fixnum? X)</procedure>2021Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.2223==== flonum?2425<procedure>(flonum? X)</procedure>2627Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.2829==== bignum?3031<procedure>(bignum? X)</procedure>3233Returns {{#t}} if {{X}} is a bignum (integer larger than fits in a34fixnum), or {{#f}} otherwise.3536==== exact-integer?3738<procedure>(exact-integer? X)</procedure>3940Returns {{#t}} if {{X}} is an exact integer (i.e., a fixnum or a41bignum), or {{#f}} otherwise.4243This procedure is compatible with the definition from the R7RS44{{(scheme base)}} library.4546==== cplxnum?4748<procedure>(cplxnum? X)</procedure>4950Returns {{#t}} if {{X}} is a true complex number (it has an imaginary51component), or {{#f}} otherwise.5253Please note that {{complex?}} will always return {{#t}} for any number54type supported by CHICKEN, so you can use this predicate if you want55to know the representational type of a number.5657==== ratnum?5859<procedure>(ratnum? X)</procedure>6061Returns {{#t}} if {{X}} is a true rational number (it is a fraction62with a denominator that's not 1), or {{#f}} otherwise.6364Please note that {{rational?}} will always return {{#t}} for any65number type supported by CHICKEN except complex numbers and non-finite66flonums, so you can use this predicate if you want to know the67representational type of a number.6869==== nan?7071<procedure>(nan? N)</procedure>7273Returns {{#t}} if {{N}} is not a number (a IEEE flonum NaN-value). If74{{N}} is a complex number, it's considered nan if it has a real or75imaginary component that's nan.7677This procedure is compatible with the definition from the R7RS78{{(scheme inexact)}} library.7980==== infinite?8182<procedure>(infinite? N)</procedure>8384Returns {{#t}} if {{N}} is negative or positive infinity, and {{#f}}85otherwise. If {{N}} is a complex number, it's considered infinite if86it has a real or imaginary component that's infinite.8788This procedure is compatible with the definition from the R7RS89{{(scheme inexact)}} library.9091==== finite?9293<procedure>(finite? N)</procedure>9495Returns {{#t}} if {{N}} represents a finite number and {{#f}}96otherwise. Positive and negative infinity as well as NaNs are not97considered finite. If {{N}} is a complex number, it's considered98finite if both the real and imaginary components are finite.99100This procedure is compatible with the definition from the R7RS101{{(scheme inexact)}} library.102103==== equal=?104105<procedure>(equal=? X y)</procedure>106107Similar to the standard procedure {{equal?}}, but compares numbers108using the {{=}} operator, so {{equal=?}} allows structural comparison109in combination with comparison of numerical data by value.110111112=== Arithmetic113114==== add1/sub1115116<procedure>(add1 N)</procedure>117<procedure>(sub1 N)</procedure>118119Adds/subtracts 1 from {{N}}.120121122==== exact-integer-nth-root123124<procedure>(exact-integer-nth-root K N)</procedure>125126Like {{exact-integer-sqrt}}, but with any base value. Calculates127{{\sqrt[N]{K}}}, the {{N}}th root of {{K}} and returns two values128{{s}} and {{r}} where {{s^N + r = K}} and {{K < (s+1)^N}}.129130131==== Division with quotient and remainder132133<procedure>(quotient&remainder X Y)</procedure>134<procedure>(quotient&modulo X Y)</procedure>135136Returns two values: the quotient and the remainder (or modulo) of137{{X}} divided by {{Y}}. Could be defined as {{(values (quotient X Y)138(remainder X Y))}}, but is much more efficient when dividing very139large numbers.140141==== signum142143<procedure>(signum N)</procedure>144145For real numbers, returns {{1}} if {{N}} is positive, {{-1}} if {{N}}146is negative or {{0}} if {{N}} is zero. {{signum}} is exactness147preserving.148149For complex numbers, returns a complex number of the same angle but150with magnitude 1.151152153=== Weak pairs154155''Weak pairs'' behave identically to regular pairs, with one156exception: the car value may be garbage collected. When that happens,157it gets replaced with a sentinel "broken-weak-pointer" value.158159They are indistinguishable from regular pairs: {{car}}, {{cdr}}, etc160all work on them, {{pair?}} returns true, etc. The {{WRITE}}161representation is identical to regular pairs, so they will be read162back as pairs. In other words, they have no read/write invariance.163164They're the same as regular pairs for all intents and purposes.165However, there's a {{weak-pair?}} predicate which ''can'' distinguish166between regular pairs and weak pairs.167168NOTE: Due to internal limitations, {{set-car!}} on a weak pair169currently may cause it to hold onto the value for one more GC cycle in170some situations.171172==== weak-cons173174<procedure>(weak-cons obj[1] obj[2])</procedure><br>175176Returns a newly allocated weak pair whose car is obj[1] and whose cdr177is obj[2]. The pair is indistinguishable from normal pairs, except as178noted above.179180 (weak-cons 'a '()) ===> (a)181 (weak-cons '(a) '(b c d)) ===> ((a) b c d)182 (weak-cons "a" '(b c)) ===> ("a" b c)183 (weak-cons 'a 3) ===> (a . 3)184 (weak-cons '(a b) 'c) ===> ((a b) . c)185186 (import (chicken gc))187188 (let* ((x '(a b))189 (y (weak-cons x 'c)))190 (gc #t)191 (car x)) ===> (a b)192193 (let ((x (weak-cons '(a b) 'c)))194 (gc #t)195 (car x)) ===> #!bwp196197As the final two examples show, when something ''else'' still holds on198to the value that's stored in the car of a weak pair, it will not be199reclaimed. But if the value is ''only'' referenced by one or more200weak pairs, it is reclaimed and the car of the weak pair is replaced201with the ''broken-weak-pointer'' value {{#!bwp}}.202203<procedure>(weak-pair? obj)</procedure><br>204205This predicate returns {{#t}} if and only if {{obj}} is a weak pair.206207 (weak-pair? (weak-cons 'a '())) ===> #t208 (weak-pair? (cons 'a '())) ===> #f209 (weak-pair? (vector 'a '())) ===> #f210211<procedure>(bwp-object? obj)</procedure>212213This predicate returns {{#t}} if {{obj}} is the broken-weak-pointer214value, otherwise {{#f}}.215216217=== Input/Output218219==== current-error-port220221<procedure>(current-error-port [PORT])</procedure>222223Returns default error output port. If {{PORT}} is given, then that224port is selected as the new current error output port.225226Note that the default error output port is not buffered. Use227[[Module (chicken port)#set-buffering-mode!|{{set-buffering-mode!}}]]228if you need a different behaviour.229230==== print231232<procedure>(print [EXP1 ...])</procedure>233234Outputs the optional arguments {{EXP1 ...}} using {{display}} and235writes a newline character to the port that is the value of236{{(current-output-port)}}. Returns {{(void)}}.237238==== print*239240<procedure>(print* [EXP1 ...])</procedure>241242Similar to {{print}}, but does not output a terminating newline243character and performs a {{flush-output}} after writing its arguments.244245246=== Interrupts and error-handling247248==== enable-warnings249250<procedure>(enable-warnings [BOOL])</procedure>251252Enables or disables warnings, depending on wether {{BOOL}} is true or253false. If called with no arguments, this procedure returns {{#t}} if254warnings are currently enabled, or {{#f}} otherwise. Note that this is255not a parameter. The current state (whether warnings are enabled or256disabled) is global and not thread-local.257258259==== error260261<procedure>(error [LOCATION] [STRING] EXP ...)</procedure>262263Prints error message, writes all extra arguments to the value of264{{(current-error-port)}} and invokes the current265exception-handler. This conforms to266[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]]. If267{{LOCATION}} is given and a symbol, it specifies the ''location'' (the268name of the procedure) where the error occurred.269270271==== assert272273<macro>(assert EXP [OBJ ...])</macro>274275Evaluates {{EXP}}, if it returns #f, {{error}} is applied to {{OBJ ...}},276else the result of {{EXP}} is returned.277When compiling in unsafe mode, assertions of this kind are disabled.278279280==== get-call-chain281282<procedure>(get-call-chain [START [THREAD]])</procedure>283284Returns a list with the call history. Backtrace information is only285generated in code compiled without {{-no-trace}} and evaluated code.286If the optional argument {{START}} is given, the backtrace starts at287this offset, i.e. when {{START}} is 1, the next to last trace-entry is288printed, and so on. If the optional argument {{THREAD}} is given, then289the call-chain will only be constructed for calls performed by this290thread.291292293294==== print-call-chain295296<procedure>(print-call-chain [PORT [START [THREAD [HEADER]]]])</procedure>297298Prints a backtrace of the procedure call history to {{PORT}}, which299defaults to {{(current-output-port)}}. The output is prefixed by the300{{HEADER}}, which defaults to {{"\n\tCall history:\n"}}.301302303==== procedure-information304305<procedure>(procedure-information PROC)</procedure>306307Returns an s-expression with debug information for the procedure308{{PROC}}, or {{#f}}, if {{PROC}} has no associated debug information.309310311==== warning312313<procedure>(warning MESSAGE [EXP ...])</procedure>314315Displays a warning message (if warnings are enabled with {{enable-warnings}}),316from the {{MESSAGE}}, and optional {{EXP}} arguments, then continues execution.317{{MESSAGE}}, and {{EXP}}, may be {{any}} object.318319320=== Lists321322==== alist-ref323324<procedure>(alist-ref KEY ALIST [TEST [DEFAULT]])</procedure>325326Looks up {{KEY}} in {{ALIST}} using {{TEST}} as the comparison function (or {{eqv?}} if327no test was given) and returns the cdr of the found pair, or {{DEFAULT}} (which defaults to {{#f}}).328329330==== alist-update331332<procedure>(alist-update KEY VALUE ALIST [TEST])</procedure>333<procedure>(alist-update! KEY VALUE ALIST [TEST])</procedure>334335If the list {{ALIST}} contains a pair of the form {{(KEY . X)}}, then this procedure336replaces {{X}} with {{VALUE}} and returns {{ALIST}}. If {{ALIST}} contains no such item, then337{{alist-update}} returns {{((KEY . VALUE) . ALIST)}}. The optional argument338{{TEST}} specifies the comparison procedure to search a matching pair in {{ALIST}}339and defaults to {{eqv?}}. {{alist-update!}} is the destructive version of {{alist-update}}.340341342==== atom?343344<procedure>(atom? X)</procedure>345346Returns {{#t}} if {{X}} is not a pair.347348349==== butlast350351<procedure>(butlast LIST)</procedure>352353Returns a fresh list with all elements but the last of {{LIST}}.354355356==== chop357358<procedure>(chop LIST N)</procedure>359360Returns a new list of sublists, where each sublist contains {{N}}361elements of {{LIST}}. If {{LIST}} has a length that is not362a multiple of {{N}}, then the last sublist contains the remaining363elements.364365<enscript highlight=scheme>366(chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6))367(chop '(a b c d) 3) ==> ((a b c) (d))368</enscript>369370371==== compress372373<procedure>(compress BLIST LIST)</procedure>374375Returns a new list with elements taken from {{LIST}} with376corresponding true values in the list {{BLIST}}.377378<enscript highlight=scheme>379(define nums '(99 100 110 401 1234))380(compress (map odd? nums) nums) ==> (99 401)381</enscript>382383384==== flatten385386<procedure>(flatten LIST1 ...)</procedure>387388Returns {{LIST1 ...}} concatenated together, with nested lists389removed (flattened).390391392==== foldl393394<procedure>(foldl PROCEDURE INIT LIST)</procedure>395396Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from397the left:398399<enscript hightlight=scheme>400(foldl + 0 '(1 2 3)) ==> (+ (+ (+ 0 1) 2) 3)401</enscript>402403Note that the order of arguments taken by {{PROCEDURE}} is different404from the {{SRFI-1}} {{fold}} procedure, but matches the more natural405order used in Haskell and Objective Caml.406407408==== foldr409410<procedure>(foldr PROCEDURE INIT LIST)</procedure>411412Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from413the right:414415<enscript hightlight=scheme>416(foldr + 0 '(1 2 3)) ==> (+ 1 (+ 2 (+ 3 0)))417</enscript>418419420==== intersperse421422<procedure>(intersperse LIST X)</procedure>423424Returns a new list with {{X}} placed between each element.425426427==== join428429<procedure>(join LISTOFLISTS [LIST])</procedure>430431Concatenates the lists in {{LISTOFLISTS}} with {{LIST}} placed432between each sublist. {{LIST}} defaults to the empty list.433434<enscript highlight=scheme>435(join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e)436(join '((p q) () (r (s) t)) '(-)) ==> (p q - - r (s) t)437</enscript>438439{{join}} could be implemented as follows:440441<enscript highlight=scheme>442(define (join lstoflsts #!optional (lst '()))443 (apply append (intersperse lstoflists lst)) )444</enscript>445446447==== rassoc448449<procedure>(rassoc KEY LIST [TEST])</procedure>450451Similar to {{assoc}}, but compares {{KEY}} with the {{cdr}} of each pair in {{LIST}} using452{{TEST}} as the comparison procedures (which defaults to {{eqv?}}).453454455==== tail?456457<procedure>(tail? X LIST)</procedure>458459Returns true if {{X}} is one of the tails (cdr's) of {{LIST}}.460461462=== Vectors463464==== vector-resize465466<procedure>(vector-resize VECTOR N [INIT])</procedure>467468Creates and returns a new vector with the contents of {{VECTOR}} and469length {{N}}. If {{N}} is greater than the original length of470{{VECTOR}}, then all additional items are initialized to {{INIT}}. If471{{INIT}} is not specified, the contents are initialized to some472unspecified value.473474475==== subvector476477<procedure>(subvector VECTOR FROM [TO])</procedure>478479Returns a new vector with elements taken from {{VECTOR}} in the480given range. {{TO}} defaults to {{(vector-length VECTOR)}}.481482{{subvector}} was introduced in CHICKEN 4.7.3.483484485=== Combinators486487488==== constantly489490<procedure>(constantly X ...)</procedure>491492Returns a procedure that always returns the values {{X ...}} regardless of the number and value of its arguments.493494<enscript highlight=scheme>495(constantly X) <=> (lambda args X)496</enscript>497498499==== complement500501<procedure>(complement PROC)</procedure>502503Returns a procedure that returns the boolean inverse of {{PROC}}.504505<enscript highlight=scheme>506(complement PROC) <=> (lambda (x) (not (PROC x)))507</enscript>508509510==== compose511512<procedure>(compose PROC1 PROC2 ...)</procedure>513514Returns a procedure that represents the composition of the515argument-procedures {{PROC1 PROC2 ...}}.516517<enscript highlight=scheme>518(compose F G) <=> (lambda args519 (call-with-values520 (lambda () (apply G args))521 F))522</enscript>523524{{(compose)}} is equivalent to {{values}}.525526527==== conjoin528529<procedure>(conjoin PRED ...)</procedure>530531Returns a procedure that returns {{#t}} if its argument satisfies the532predicates {{PRED ...}}.533<enscript highlight=scheme>534((conjoin odd? positive?) 33) ==> #t535((conjoin odd? positive?) -33) ==> #f536</enscript>537538539==== disjoin540541<procedure>(disjoin PRED ...)</procedure>542543Returns a procedure that returns {{#t}} if its argument satisfies any544predicate {{PRED ...}}.545<enscript highlight=scheme>546((disjoin odd? positive?) 32) ==> #t547((disjoin odd? positive?) -32) ==> #f548</enscript>549550551==== each552553<procedure>(each PROC ...)</procedure>554555Returns a procedure that applies {{PROC ...}} to its arguments, and returns the result(s)556of the last procedure application. For example557558<enscript highlight=scheme>559(each pp eval)560</enscript>561562is equivalent to563564<enscript highlight=scheme>565(lambda args566 (apply pp args)567 (apply eval args) )568</enscript>569570{{(each PROC)}} is equivalent to {{PROC}} and {{(each)}} is equivalent to571{{void}}.572573574==== flip575576<procedure>(flip PROC)</procedure>577578Returns a two-argument procedure that calls {{PROC}} with its579arguments swapped:580<enscript highlight=scheme>581(flip PROC) <=> (lambda (x y) (PROC y x))582</enscript>583584585==== identity586587<procedure>(identity X)</procedure>588589Returns its sole argument {{X}}.590591592==== list-of?593594<procedure>(list-of? PRED)</procedure>595596Returns a procedure of one argument that returns {{#t}} when597applied to a list of elements that all satisfy the predicate procedure598{{PRED}}, or {{#f}} otherwise.599600<enscript highlight=scheme>601((list-of? even?) '(1 2 3)) ==> #f602((list-of? number?) '(1 2 3)) ==> #t603</enscript>604605606==== o607608<procedure>(o PROC ...)</procedure>609610A single value version of {{compose}} (slightly faster). {{(o)}} is equivalent611to {{identity}}.612613614=== UNICODE case folding615616==== char-foldcase617618<procedure>(char-foldcase CHAR)</procedure>619620Performs simple UNICODE case folding to {{CHAR}}, language-specific mappings621are not used.622623==== string-foldcase624625<procedure>(string-foldcase STRING)</procedure>626627Performs UNICODE case folding to {{STRING}}, language-specific mappings628are not used. The resulting string may be longer than the original string.629630631=== User-defined named characters632633==== char-name634635<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>636637This procedure can be used to inquire about character names or to638define new ones. With a single argument the behavior is as follows:639If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns640the character with this name, or {{#f}} if no character is defined641under this name. If {{SYMBOL-OR-CHAR}} is a character, then the642name of the character is returned as a symbol, or {{#f}} if the643character has no associated name.644645If the optional argument {{CHAR}} is provided, then646{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of647the given character. If multiple names designate the same character,648then the {{write}} will use the character name that was defined last.649650<enscript highlight=scheme>651(char-name 'space) ==> #\space652(char-name #\space) ==> space653(char-name 'bell) ==> #f654(char-name (integer->char 7)) ==> #f655(char-name 'bell (integer->char 7))656(char-name 'bell) ==> #\bell657(char->integer (char-name 'bell)) ==> 7658</enscript>659660661=== The unspecified value662663==== void664665<procedure>(void ARGUMENT ...)</procedure>666667Ignores {{ARGUMENT ...}} and returns an unspecified value.668669670=== Continuations671672==== call/cc673674<procedure>(call/cc PROCEDURE)</procedure>675676An alias for {{call-with-current-continuation}}.677678This procedure is compatible with the definition from the R7RS679{{(scheme base)}} library.680681=== Symbols682683==== Symbol utilities684685===== symbol-append686687<procedure>(symbol-append SYMBOL1 ...)</procedure>688689Creates a new symbol from the concatenated names of the argument symbols690{{(SYMBOL1 ...)}}.691692==== Uninterned symbols ("gensyms")693694Symbols may be "interned" or "uninterned". Interned symbols are695registered in a global table, and when read back from a port are696identical to a symbol written before:697698<enscript highlight=scheme>699(define sym 'foo)700701(eq? sym (with-input-from-string702 (with-output-to-string703 (lambda () (write sym)))704 read))705706 => #t707</enscript>708709Uninterned symbols on the other hand are not globally registered and so710multiple symbols with the same name may coexist:711712<enscript highlight=scheme>713(define sym (gensym 'foo)) ; sym is a uninterned symbol like "foo42"714715(eq? sym (with-input-from-string ; the symbol read will be an interned symbol716 (with-output-to-string717 (lambda () (write sym)))718 read))719720 => #f721722(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))723724 => #f725</enscript>726727Use uninterned symbols if you need to generate unique values that728can be compared quickly, for example as keys into a hash-table729or association list. Note that uninterned symbols lose their730uniqueness property when written to a file and read back in, as731in the example above.732733===== gensym734735<procedure>(gensym [STRING-OR-SYMBOL])</procedure>736737Returns a newly created uninterned symbol. If an argument is provided,738the new symbol is prefixed with that argument.739740741===== string->uninterned-symbol742743<procedure>(string->uninterned-symbol STRING)</procedure>744745Returns a newly created, unique symbol with the name {{STRING}}.746747748=== Setters749750SRFI-17 is fully implemented. For more information see:751[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].752753==== setter754755<procedure>(setter PROCEDURE)</procedure>756757Returns the setter-procedure of {{PROCEDURE}}, or signals an error if758{{PROCEDURE}} has no associated setter-procedure.759760Note that {{(set! (setter PROC) ...)}} for a procedure that has no761associated setter procedure yet is a very slow operation (the old762procedure is replaced by a modified copy, which involves a garbage763collection).764765766==== getter-with-setter767768<procedure>(getter-with-setter GETTER SETTER)</procedure>769770Returns a copy of the procedure {{GETTER}} with the associated setter771procedure {{SETTER}}. Contrary to the SRFI specification, the setter772of the returned procedure may be changed.773774775=== Binding forms for optional arguments776777==== optional778779<macro>(optional ARGS DEFAULT)</macro>780781Use this form for procedures that take a single optional argument. If782{{ARGS}} is the empty list {{DEFAULT}} is evaluated and783returned, otherwise the first element of the list {{ARGS}}. It is784an error if {{ARGS}} contains more than one value.785786<enscript highlight=scheme>787(define (incr x . i) (+ x (optional i 1)))788(incr 10) ==> 11789(incr 12 5) ==> 17790</enscript>791792793==== let-optionals794795<macro> (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)</macro>796797Binding constructs for optional procedure arguments. {{ARGS}} is798normally a rest-parameter taken from a lambda-list. {{let-optionals}}799binds {{VAR1 ...}} to available arguments in parallel, or to800{{DEFAULT1 ...}} if not enough arguments were provided.801{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable802sees the previous ones. it is an error if any excess arguments are803provided.804805<enscript highlight=scheme>806(let-optionals '(one two) ((a 1) (b 2) (c 3))807 (list a b c) ) ==> (one two 3)808</enscript>809810==== let-optionals*811812<macro> (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)</macro>813814Binding constructs for optional procedure arguments. {{ARGS}} is815normally a rest-parameter taken from a lambda-list. {{let-optionals}}816binds {{VAR1 ...}} to available arguments in parallel, or to817{{DEFAULT1 ...}} if not enough arguments were provided.818{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable819sees the previous ones. If a single variable {{RESTVAR}} is given,820then it is bound to any remaining arguments, otherwise it is an error821if any excess arguments are provided.822823<enscript highlight=scheme>824(let-optionals* '(one two) ((a 1) (b 2) (c a))825 (list a b c) ) ==> (one two one)826</enscript>827828=== Other binding forms829830==== and-let*831832<macro>(and-let* (BINDING ...) EXP1 EXP2 ...)</macro>833834Bind sequentially and execute body. {{BINDING}} can835be a list of a variable and an expression, a list with a single836expression, or a single variable. If the value of an expression837bound to a variable is {{#f}}, the {{and-let*}} form838evaluates to {{#f}} (and the subsequent bindings and the body839are not executed). Otherwise the next binding is performed. If840all bindings/expressions evaluate to a true result, the body is841executed normally and the result of the last expression is the842result of the {{and-let*}} form. See also the documentation for843[[http://srfi.schemers.org/srfi-2/srfi-2.html|SRFI-2]].844845==== letrec*846847<macro>(letrec* ((VARIABLE EXPRESSION) ...) BODY ...)</macro>848849Implements R6RS/R7RS {{letrec*}}. {{letrec*}} is similar to {{letrec}}850but binds the variables sequentially and is to {{letrec}} what851{{let*}} is to {{let}}.852853This special form is compatible with the definition from the R7RS854{{(scheme base)}} library.855856==== rec857858<macro>(rec NAME EXPRESSION)</macro><br>859<macro>(rec (NAME VARIABLE ...) BODY ...)</macro>860861Allows simple definition of recursive definitions. {{(rec NAME EXPRESSION)}} is862equivalent to {{(letrec ((NAME EXPRESSION)) NAME)}} and {{(rec (NAME VARIABLE ...) BODY ...)}}863is the same as {{(letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME)}}.864865==== cut866867<macro>(cut SLOT ...)</macro><br>868<macro>(cute SLOT ...)</macro>869870[[http://srfi.schemers.org/srfi-26/srfi-26.html|Syntactic sugar for specializing parameters]].871872==== define-values873874<macro>(define-values (NAME ...) VALUEEXP)</macro>875<macro>(define-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>876<macro>(define-values NAME VALUEEXP)</macro>877878Defines several variables at once, with the result values of expression879{{VALUEEXP}}, similar to {{set!-values}}.880881This special form is compatible with the definition from the R7RS882{{(scheme base)}} library.883884==== fluid-let885886<macro>(fluid-let ((VAR1 X1) ...) BODY ...)</macro>887888Binds the variables {{VAR1 ...}} dynamically to the values {{X1 ...}}889during execution of {{BODY ...}}. This implements890[[http://srfi.schemers.org/srfi-15/srfi-15.html|SRFI-15]].891892==== let-values893894<macro>(let-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>895896Binds multiple variables to the result values of {{VALUEEXP ...}}.897All variables are bound simultaneously. Like {{define-values}}, the898{{(NAME ...)}} expression can be any basic lambda list (dotted tail899notation is supported).900901This special form implements902[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]], and it is903also compatible with the definition from the R7RS {{(scheme base)}}904library.905906907==== let*-values908909<macro>(let*-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>910911Binds multiple variables to the result values of {{VALUEEXP ...}}.912The variables are bound sequentially. Like {{let-values}}, the913{{(NAME ...)}} expression can be any basic lambda list (dotted tail914notation is supported).915916This is also part of917[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]] and is also918compatible with the definition from the R7RS {{(scheme base)}}919library.920921<enscript highlight=scheme>922(let*-values (((a b) (values 2 3))923 ((p) (+ a b)) )924 p) ==> 5925</enscript>926927==== letrec-values928929<macro>(letrec-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>930931Binds the result values of {{VALUEEXP ...}} to multiple variables at932once. All variables are mutually recursive. Like {{let-values}}, the933{{(NAME ...)}} expression can be any basic lambda list (dotted tail934notation is supported).935936<enscript highlight=scheme>937(letrec-values (((odd even)938 (values939 (lambda (n) (if (zero? n) #f (even (sub1 n))))940 (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )941 (odd 17) ) ==> #t942</enscript>943944945==== receive946947<macro>(receive (NAME ...) VALUEEXP BODY ...)</macro><br>948<macro>(receive (NAME1 ... NAMEn . NAMEn+1) VALUEEXP BODY ...)</macro><br>949<macro>(receive NAME VALUEEXP BODY ...)</macro><br>950<macro>(receive VALUEEXP)</macro>951952[[http://srfi.schemers.org/srfi-8/srfi-8.html|SRFI-8]].953Syntactic sugar for {{call-with-values}}. Binds variables954to the result values of {{VALUEEXP}} and evaluates {{BODY ...}},955similar {{define-values}} but lexically scoped.956957{{(receive VALUEEXP)}} is equivalent to {{(receive _ VALUEEXP _)}}.958This shortened form is not described by SRFI-8.959960==== set!-values961962<macro>(set!-values (NAME ...) VALUEEXP)</macro>963<macro>(set!-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>964<macro>(set!-values NAME VALUEEXP)</macro>965966Assigns the result values of expression {{VALUEEXP}} to multiple967variables, similar to {{define-values}}.968969==== nth-value970971<macro>(nth-value N EXP)</macro>972973Returns the {{N}}th value (counting from zero) of the values returned974by expression {{EXP}}.975976977=== Substitution forms and macros978979==== define-constant980981<macro>(define-constant NAME CONST)</macro>982983Defines a variable with a constant value, evaluated at compile-time.984Any reference to such a constant should appear textually '''after'''985its definition. This construct is equivalent to {{define}} when986evaluated or interpreted. Constant definitions should only appear at987toplevel. Note that constants are local to the current compilation988unit and are not available outside of the source file in which they989are defined. Names of constants still exist in the Scheme namespace990and can be lexically shadowed. If the value is mutable, then the991compiler is careful to preserve its identity. {{CONST}} may be any992constant expression, and may also refer to constants defined via993{{define-constant}} previously, but it must be possible to994evaluate the expression at compile-time.995996==== define-inline997998<macro>(define-inline (NAME VAR ...) BODY ...)</macro><br>999<macro>(define-inline (NAME VAR ... . VAR) BODY ...)</macro><br>1000<macro>(define-inline NAME EXP)</macro>10011002Defines an inline procedure. Any occurrence of {{NAME}} will be replaced1003by {{EXP}} or {{(lambda (VAR ... [. VAR]) BODY ...)}}. This is similar1004to a macro, but variable names and scope are handled correctly.10051006Inline substitutions take place '''after''' macro-expansion, and any1007reference to {{NAME}} should appear textually '''after''' its1008definition. Inline procedures are local to the current compilation unit1009and are not available outside of the source file in which they are1010defined. Names of inline procedures still exist in the Scheme namespace1011and can be lexically shadowed. Inline definitions should only appear at1012the toplevel.10131014Note that the {{inline-limit}} compiler option does not affect inline1015procedure expansion, and self-referential inline procedures may cause1016the compiler to enter an infinite loop.10171018In the third form, {{EXP}} must be a lambda expression.10191020This construct is equivalent to {{define}} when evaluated or1021interpreted.102210231024=== Conditional forms10251026==== unless10271028<macro>(unless TEST EXP1 EXP2 ...)</macro>10291030Equivalent to:10311032<enscript highlight=scheme>1033(if (not TEST) (begin EXP1 EXP2 ...))1034</enscript>10351036==== when10371038<macro>(when TEST EXP1 EXP2 ...)</macro>10391040Equivalent to:10411042<enscript highlight=scheme>1043(if TEST (begin EXP1 EXP2 ...))1044</enscript>10451046=== Record structures10471048==== define-record10491050<macro>(define-record NAME SLOTNAME ...)</macro>10511052Defines a record type. This defines a number of procedures for1053creating, accessing, and modifying record members.10541055Call {{make-NAME}} to create an instance1056of the structure (with one initialization-argument for each slot, in1057the listed order).10581059{{(NAME? STRUCT)}} tests any object for being an instance of this1060structure.10611062Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}1063and updated using {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.10641065<enscript highlight=scheme>1066(define-record point x y)1067(define p1 (make-point 123 456))1068(point? p1) ==> #t1069(point-x p1) ==> 1231070(point-y-set! p1 99)1071(point-y p1) ==> 991072</enscript>10731074===== SRFI-17 setters10751076{{SLOTNAME}} may alternatively also be of the form10771078 (setter SLOTNAME)10791080In this case the slot can be read with {{(NAME-SLOTNAME STRUCT)}} as usual,1081and modified with {{(set! (NAME-SLOTNAME STRUCT) VALUE)}} (the slot-accessor1082has an associated SRFI-17 "setter" procedure) instead of1083the usual {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.108410851086<enscript highlight=scheme>1087(define-record point (setter x) (setter y))1088(define p1 (make-point 123 456))1089(point? p1) ==> #t1090(point-x p1) ==> 1231091(set! (point-y p1) 99)1092(point-y p1) ==> 991093</enscript>10941095==== define-record-type10961097<macro>(define-record-type NAME (CONSTRUCTOR TAG ...) PREDICATE (FIELD ACCESSOR [MODIFIER]) ...)</macro>10981099SRFI-9 record types. For more information see the documentation for1100[[http://srfi.schemers.org/srfi-9/srfi-9.html|SRFI-9]].11011102As an extension the {{MODIFIER}} may have the form1103{{(setter PROCEDURE)}}, which will define a SRFI-17 setter-procedure1104for the given {{PROCEDURE}} that sets the field value.1105Usually {{PROCEDURE}} has the same name is {{ACCESSOR}} (but it1106doesn't have to).11071108This special form is also compatible with the definition from the R7RS1109{{(scheme base)}} library.11101111==== record-printer11121113<procedure>(record-printer NAME)</procedure><br>11141115Returns the procedure used to print records of the type {{NAME}} if1116one has been set with {{set-record-printer!}}, {{#f}} otherwise.11171118==== set-record-printer!11191120<procedure>(set-record-printer! NAME PROCEDURE)</procedure><br>1121<procedure>(set! (record-printer NAME) PROCEDURE)</procedure>11221123Defines a printing method for record of the type {{NAME}} by1124associating a procedure with the record type. When a record of this1125type is written using {{display, write}} or {{print}}, then1126the procedure is called with two arguments: the record to be printed1127and an output-port.11281129<enscript highlight=scheme>1130(define-record-type foo (make-foo x y z) foo?1131 (x foo-x)1132 (y foo-y)1133 (z foo-z))1134(define f (make-foo 1 2 3))1135(set-record-printer! foo1136 (lambda (x out)1137 (fprintf out "#,(foo ~S ~S ~S)"1138 (foo-x x) (foo-y x) (foo-z x))))1139(define-reader-ctor 'foo make-foo)1140(define s (with-output-to-string1141 (lambda () (write f))))1142s ==> "#,(foo 1 2 3)"1143(equal? f (with-input-from-string1144 s read))) ==> #t1145</enscript>11461147=== Other forms11481149==== load11501151<procedure>(load filename [evalproc])</procedure><br>11521153Filename should be a string naming an existing file containing Scheme1154source code. The load procedure reads expressions and definitions from1155the file and evaluates them sequentially. It is unspecified whether the1156results of the expressions are printed. The load procedure does not1157affect the values returned by current-input-port and1158current-output-port. Load returns an unspecified value.11591160CHICKEN offers a few extensions to the R7RS definition of {{load}}:11611162* The {{filename}} may also be an input port.1163* The expressions which are read one by one from the source file are passed to the procedure indicated by the extra optional {{evalproc}} argument, which defaults to {{eval}}.1164* On platforms that support it (currently BSD, Haiku, MacOS X, Linux, Solaris, and Windows), {{load}} can be used to load shared objects.11651166Example for loading compiled programs:11671168 % cat x.scm1169 (define (hello) (print "Hello!"))1170 % csc -s x.scm1171 % csi -q1172 #;1> (load "x.so")1173 ; loading x.so ...1174 #;2> (hello)1175 Hello!1176 #;3>11771178There are some limitations and caveats to the CHICKEN extensions you1179need to be aware of:11801181* The second argument to {{load}} is ignored when loading compiled code.1182* If source code is loaded from a port, then that port is closed after all expressions have been read.1183* A compiled file can only be loaded once. Subsequent attempts to load the same file have no effect.11841185==== include11861187<macro>(include STRING1 STRING2 ...)</macro>1188<macro>(include-ci STRING1 STRING2 ...)</macro>11891190Include toplevel-expressions from the given source files in the currently1191compiled/interpreted program. If the included file has the extension1192{{.scm}}, then it may be omitted. The file is searched for in the1193current directory and all directories specified by the {{-include-path}}1194option.11951196{{include-ci}} works as {{include}} but reads files in case-insensitive1197mode.11981199==== include-relative12001201<macro>(include-relative STRING)</macro>12021203Works like {{include}}, but the filename is searched for relative to the1204including file rather than the current directory.120512061207=== Making extra libraries and extensions available12081209==== require-extension12101211<macro>(require-extension ID ...)</macro>12121213This is equivalent to {{(require-library ID ...)}} but performs an implicit1214{{import}}, if necessary. Since version 4.4.0, {{ID}} may also be an import specification1215(using {{rename}}, {{only}}, {{except}} or {{prefix}}).12161217To make long matters short - just use {{require-extension}} and it will normally figure everything out for dynamically1218loadable extensions and core library units.12191220This implementation of {{require-extension}} is compliant with [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]]1221(see the [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]] document for more information).122212231224==== require-library12251226<macro>(require-library ID ...)</macro>12271228This form does all the necessary steps to make the libraries or extensions given1229in {{ID ...}} available. It loads syntactic extensions, if needed and generates1230code for loading/linking with core library modules or separately installed1231extensions.12321233During interpretation/evaluation {{require-library}} performs one of the1234following:12351236* If {{ID}} names a built-in feature, then nothing is done.1237* If {{ID}} names one of the syntactic extensions {{chicken-syntax chicken-ffi-syntax}}, then this extension will be loaded.1238* If {{ID}} names one of the core library units shipped with CHICKEN, then a {{(load-library 'ID)}} will be performed.1239* If {{ID}} names an installed extension with the {{syntax}} or {{require-at-runtime}} attribute, then the extensions is loaded at compile-time, probably doing a run-time {{(require ...)}} for any run-time requirements.1240* Otherwise, {{(require-library ID)}} is equivalent to {{(require 'ID)}}.12411242During compilation, one of the following happens instead:12431244* If {{ID}} names a built-in feature, then nothing is done.1245* If {{ID}} names one of the syntactic extensions {{chicken-syntax chicken-ffi-syntax}}, then this extension will be loaded at compile-time, making the syntactic extensions available in compiled code.1246* If {{ID}} names one of the core library units shipped with CHICKEN, or if the option {{-uses ID}} has been passed to the compiler, then a {{(declare (uses ID))}} is generated.1247* If {{ID}} names an installed extension with the {{syntax}} or {{require-at-runtime}} attribute, then the extension is loaded at compile-time, and code is emitted to {{(require ...)}} any needed run-time requirements.1248* Otherwise {{(require-library ID)}} is equivalent to {{(require 'ID)}}.12491250{{ID}} should be a pure extension name and should not contain any path prefixes (for example {{dir/lib...}} is illegal).12511252{{ID}} may also be a list that designates an extension-specifier. Currently the following extension specifiers are1253defined:12541255* {{(srfi NUMBER ...)}} is required for SRFI-55 compatibility and is fully implemented1256* {{(version ID NUMBER)}} is equivalent to {{ID}}, but checks at compile-time whether the extension named {{ID}} is installed and whether its version is equal or higher than {{NUMBER}}. {{NUMBER}} may be a string or a number, the comparison is done lexicographically (using {{string>=?}}).12571258=== Process shutdown12591260==== emergency-exit12611262<procedure>(emergency-exit [CODE])</procedure>12631264Exits the current process without flushing any buffered output (using1265the C function {{_exit}}). Note that the {{exit-handler}} is not called1266when this procedure is invoked. The optional exit status code {{CODE}}1267defaults to {{0}}.126812691270==== exit12711272<procedure>(exit [CODE])</procedure>12731274Exit the running process and return exit-code, which defaults to 01275(Invokes {{exit-handler}}).12761277Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.127812791280=== exit-handler12811282<parameter>(exit-handler)</parameter>12831284A procedure of a single optional argument. When {{exit}} is called,1285then this procedure will be invoked with the exit-code as argument. The1286default behavior is to terminate the program.12871288Note that this handler is ''not'' invoked when {{emergency-exit}} is1289used.129012911292=== implicit-exit-handler12931294<parameter>(implicit-exit-handler)</parameter>12951296A procedure of no arguments. When the last toplevel expression of the1297program has executed, then the value of this parameter is called. The1298default behaviour is to invoke all pending finalizers.129913001301==== on-exit13021303<procedure>(on-exit THUNK)</procedure>13041305Schedules the zero-argument procedures {{THUNK}} to be executed before1306the process exits, either explicitly via {{exit}} or implicitly after1307execution of the last top-level form. Note that finalizers for1308unreferenced finalized data are run before exit procedures.130913101311=== System interface131213131314==== sleep13151316<procedure>(sleep SECONDS)</procedure>13171318Puts the program to sleep for {{SECONDS}}. If the scheduler is loaded1319(for example when srfi-18 is in use) then only the calling thread is put1320to sleep and other threads may continue executing. Otherwise, the whole1321process is put to sleep.132213231324=== File Input/Output13251326==== flush-output13271328<procedure>(flush-output [PORT])</procedure>13291330Write buffered output to the given output-port. {{PORT}} defaults1331to the value of {{(current-output-port)}}.13321333=== Port predicates13341335==== port-closed?13361337<procedure>(port-closed? PORT)</procedure>13381339Is the given {{PORT}} closed (in all directions)?134013411342=== Built-in parameters13431344Certain behavior of the interpreter and compiled programs can be1345customized via the following built-in parameters:13461347==== case-sensitive13481349<parameter>(case-sensitive)</parameter>13501351If true, then {{read}} reads symbols and identifiers in1352case-sensitive mode and uppercase characters in symbols are printed1353escaped. Defaults to {{#t}}.135413551356==== keyword-style13571358<parameter>(keyword-style)</parameter>13591360Enables alternative keyword syntax, where {{STYLE}} may be either1361{{#:prefix}} (as in Common Lisp), which recognizes symbols beginning1362with a colon as keywords, or {{#:suffix}} (as in DSSSL), which recognizes1363symbols ending with a colon as keywords.1364Any other value disables the alternative syntaxes. In the interpreter1365the default is {{#:suffix}}.136613671368==== parentheses-synonyms13691370<parameter>(parentheses-synonyms)</parameter>13711372If true, then the list delimiter synonyms {{#\[}} {{#\]}} and {{#\{}} {{#\}}} are enabled. Defaults to {{#t}}.137313741375==== symbol-escape13761377<parameter>(symbol-escape)</parameter>13781379If true, then the symbol escape {{#\|}} {{#\|}} is allowed when reading1380and printing expressions. Defaults to {{#t}}.138113821383---1384Previous: [[Module srfi-4]]13851386Next: [[Module (chicken bitwise)]]